

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  
  <title>Rigid Body Dynamics &mdash; NVIDIA PhysX SDK 4.1 Documentation</title>
  

  
  <link rel="shortcut icon" href="_static/images/favicon.ico"/>

  
  

  

  
  
    

  
  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../_static/breathe.css" type="text/css" />
    <link rel="next" title="Simulation" href="Simulation.html" />
    <link rel="prev" title="Rigid Body Collision" href="RigidBodyCollision.html" />
    <link href="../_static/css/nvidia_theme.css" rel="stylesheet" type="text/css">
    
    
        <style>
            .wy-nav-content::before {
                content: "PhysX 4.1 SDK Guide";
            }
        </style>
    


  
  <script src="../_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="../Index.html" class="icon icon-home"> Python
          

          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="Index.html">User's Guide</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="License.html">PhysX License</a></li>
<li class="toctree-l2"><a class="reference internal" href="Introduction.html">Welcome to PhysX</a></li>
<li class="toctree-l2"><a class="reference internal" href="HelloWorld.html">Snippets</a></li>
<li class="toctree-l2"><a class="reference internal" href="BuildingWithPhysX.html">Building with PhysX</a></li>
<li class="toctree-l2"><a class="reference internal" href="API.html">The PhysX API</a></li>
<li class="toctree-l2"><a class="reference internal" href="Startup.html">Startup and Shutdown</a></li>
<li class="toctree-l2"><a class="reference internal" href="Threading.html">Threading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Geometry.html">Geometry</a></li>
<li class="toctree-l2"><a class="reference internal" href="RigidBodyOverview.html">Rigid Body Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html">Rigid Body Collision</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="">Rigid Body Dynamics</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#velocity">Velocity</a></li>
<li class="toctree-l3"><a class="reference internal" href="#mass-properties">Mass Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="#applying-forces-and-torques">Applying Forces and Torques</a></li>
<li class="toctree-l3"><a class="reference internal" href="#gravity">Gravity</a></li>
<li class="toctree-l3"><a class="reference internal" href="#friction-and-restitution">Friction and Restitution</a></li>
<li class="toctree-l3"><a class="reference internal" href="#sleeping">Sleeping</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#sleep-state-change-events">Sleep state change events</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#kinematic-actors">Kinematic Actors</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#kinematic-surface-velocities">Kinematic Surface Velocities</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#active-actors">Active Actors</a></li>
<li class="toctree-l3"><a class="reference internal" href="#dominance">Dominance</a></li>
<li class="toctree-l3"><a class="reference internal" href="#solver-iterations">Solver Iterations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#immediate-mode">Immediate Mode</a></li>
<li class="toctree-l3"><a class="reference internal" href="#enhanced-determinism">Enhanced Determinism</a></li>
<li class="toctree-l3"><a class="reference internal" href="#axis-locking">Axis locking</a></li>
<li class="toctree-l3"><a class="reference internal" href="#temporal-gauss-seidel">Temporal Gauss-Seidel</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="Simulation.html">Simulation</a></li>
<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html">Advanced Collision Detection</a></li>
<li class="toctree-l2"><a class="reference internal" href="Joints.html">Joints</a></li>
<li class="toctree-l2"><a class="reference internal" href="Articulations.html">Articulations</a></li>
<li class="toctree-l2"><a class="reference internal" href="Articulations.html#maximal-coordinate-and-reduced-articulations">Maximal Coordinate and Reduced Articulations</a></li>
<li class="toctree-l2"><a class="reference internal" href="Articulations.html#maximal-coordinate-articulations">Maximal Coordinate Articulations</a></li>
<li class="toctree-l2"><a class="reference internal" href="Articulations.html#reduced-coordinate-articulations">Reduced Coordinate Articulations</a></li>
<li class="toctree-l2"><a class="reference internal" href="OriginShift.html">Scene Origin</a></li>
<li class="toctree-l2"><a class="reference internal" href="GPURigidBodies.html">GPU Rigid Bodies</a></li>
<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html">Geometry Queries</a></li>
<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html">Scene Queries</a></li>
<li class="toctree-l2"><a class="reference internal" href="Vehicles.html">Vehicles</a></li>
<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html">Character Controllers</a></li>
<li class="toctree-l2"><a class="reference internal" href="DebugVisualization.html">Debug Visualization</a></li>
<li class="toctree-l2"><a class="reference internal" href="VisualDebugger.html">PhysX Visual Debugger (PVD)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Statistics.html">Simulation Statistics</a></li>
<li class="toctree-l2"><a class="reference internal" href="Serialization.html">Serialization</a></li>
<li class="toctree-l2"><a class="reference internal" href="ExtendingSerialization.html">Extending Serialization</a></li>
<li class="toctree-l2"><a class="reference internal" href="BestPractices.html">Best Practices Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html">Migrating From PhysX SDK 2.x to 3.x</a></li>
<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html">Migrating From PhysX SDK 3.2 to 3.3</a></li>
<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html">Migrating From PhysX SDK 3.3 to 3.4</a></li>
<li class="toctree-l2"><a class="reference internal" href="MigrationTo40.html">Migrating From PhysX SDK 3.4 to 4.0</a></li>
</ul>
</li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../Index.html">Python</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../Index.html">Docs</a> &raquo;</li>
        
          <li><a href="Index.html">User's Guide</a> &raquo;</li>
        
      <li>Rigid Body Dynamics</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="rigid-body-dynamics">
<span id="rigidbodydynamics"></span><h1>Rigid Body Dynamics<a class="headerlink" href="#rigid-body-dynamics" title="Permalink to this headline">¶</a></h1>
<p>In this chapter we cover a number of topics that are also important to understand once you are comfortable with setting up a basic rigid body simulation world.</p>
<div class="section" id="velocity">
<h2>Velocity<a class="headerlink" href="#velocity" title="Permalink to this headline">¶</a></h2>
<p>A rigid body's motion is separated into linear and angular velocity components. During simulation, PhysX will modify the velocity of an object in accordance with gravity, other applied forces and torques and as a result of various constraints, such as collisions or joints.</p>
<p>A body's linear and angular velocities can be read using the following methods:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVec3</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">getLinearVelocity</span><span class="p">();</span>
<span class="n">PxVec3</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">getAngularVelocity</span><span class="p">();</span>
</pre></div>
</div>
<p>A body's linear and angular velocities can be set using the following methods:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">setLinearVelocity</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">linVel</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span>
<span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">setAngularVelocity</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">angVel</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="mass-properties">
<h2>Mass Properties<a class="headerlink" href="#mass-properties" title="Permalink to this headline">¶</a></h2>
<p>A dynamic actor needs mass properties: the mass, moment of inertia, and the center of mass frame which specifies the position of the actor's center of mass and its principal inertia axes. The easiest way to calculate mass properties is to use the PxRigidBodyExt::updateMassAndInertia() helper function, which will set all three properties based on the actor's shapes and a uniform density value. Variants of this function allow combinations of per-shape densities and manual specification of some mass properties. See the reference for PxRigidBodyExt for more details.</p>
<p>The Wobbly Snowmen in the North Pole Sample illustrate the use of different mass properties.  The snowmen act like roly-poly toys, which are usually just an empty shell with the bottom filled with some heavy material. The low centers of mass cause them to move back to an upright position after they have been tilted. They come in different flavors, depending on how the mass properties are set:</p>
<p>The first is basically massless. There is just a little sphere with a relatively high mass at the bottom of the Actor. This results in a quite rapid movement due to the small resulting moments of inertia. The snowman feels light.</p>
<p>The second uses the mass of the bottom snowball only, resulting in a bigger inertia. Later on, the center of mass is moved to the bottom of the actor. This approximation is by no means physically correct, but the resulting snowman feels a bit more filled.</p>
<p>The third and fourth snowman use shapes to calculate the mass. The difference is that one calculates the moments of inertia first (from the real center of mass) and then the center of mass is moved to the bottom. The other calculates the moments of inertia about the low center of mass that we pass to the calculation routine. Note how much slower the wobbling is for the second case although both have the same mass. This is because the head accounts for much more in the moment of inertia (the distance from the center of mass squared).</p>
<p>The last snowman's mass properties are set up manually. The sample uses rough values for the moment of inertia to create a specific desired behavior. The diagonal tensor has a low value in X, and high values in Y and Z, producing a low resistance to rotation around the X-axis and high resistance around Y and Z. As a consequence, the snowman will wobble back and forth only around the X axis.</p>
<p>If you have a 3x3 inertia matrix (for example, you have real-life inertia tensors for your objects) use the PxDiagonalize() function to obtain principal axes and diagonal inertia tensors to initialize PxRigidDynamic actors.</p>
<p>When manually setting the mass/inertia tensor of bodies, PhysX requires positive values for the mass and each principal axis of inertia. However, it is legal to provide 0s in these values. When provided with a 0 mass or inertia value, PhysX interprets this to mean infinite mass or inertia around that principal axis. This can be used to create bodies that resist all linear motion or that resist all or some angular motion. Examples of the effects that could be achieved using this approach are:</p>
<ul class="simple">
<li>Bodies that behave as if they were kinematic.</li>
<li>Bodies whose translation behaves kinematically but whose rotation is dynamic.</li>
<li>Bodies whose translation is dynamic but whose rotation is kinematic.</li>
<li>Bodies which can only rotate around a specific axis.</li>
</ul>
<p>Some examples of what could be achieved are detailed below. First, let's assume that we are creating a common structure - a windmill. The code to construct the bodies that would be part of the windmill are provided below:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">dyn</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">2.5f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">)));</span>
<span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">dyn</span><span class="p">,</span> <span class="n">PxBoxGeometry</span><span class="p">(</span><span class="mf">2.f</span><span class="p">,</span> <span class="mf">0.2f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">),</span> <span class="n">material</span><span class="p">);</span>
<span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">dyn</span><span class="p">,</span> <span class="n">PxBoxGeometry</span><span class="p">(</span><span class="mf">0.2f</span><span class="p">,</span> <span class="mf">2.f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">),</span> <span class="n">material</span><span class="p">);</span>
<span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setActorFlag</span><span class="p">(</span><span class="n">PxActorFlag</span><span class="o">::</span><span class="n">eDISABLE_GRAVITY</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span>
<span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setAngularVelocity</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">,</span> <span class="mf">5.f</span><span class="p">));</span>
<span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setAngularDamping</span><span class="p">(</span><span class="mf">0.f</span><span class="p">);</span>
<span class="n">PxRigidStatic</span><span class="o">*</span> <span class="n">st</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="p">.</span><span class="n">createRigidStatic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">1.5f</span><span class="p">,</span> <span class="o">-</span><span class="mf">1.f</span><span class="p">)));</span>
<span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">t</span><span class="p">,</span> <span class="n">PxBoxGeometry</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">,</span> <span class="mf">1.5f</span><span class="p">,</span> <span class="mf">0.8f</span><span class="p">),</span> <span class="n">material</span><span class="p">);</span>
<span class="n">scene</span><span class="p">.</span><span class="n">addActor</span><span class="p">(</span><span class="n">dyn</span><span class="p">);</span>
<span class="n">scene</span><span class="p">.</span><span class="n">addActor</span><span class="p">(</span><span class="n">st</span><span class="p">);</span>
</pre></div>
</div>
<p>The above code creates a static box frame for the windmill and a cross to represent the blades of the turbine. We turn off gravity and angular damping on the windmill blade and give it an initial angular velocity. As a result, this turbine blade will rotate at a constant angular velocity indefinitely. However, if another object collided with the turbine, our windmill would cease to function correctly because the turbine blade would be knocked out of place. There are several options to make the turbine blade stay in the correct position when other bodies interact with it. One such approach might be to make the turbine have infinite mass and inertia. In this case, any interactions with bodies would not affect the turbine at all:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setMass</span><span class="p">(</span><span class="mf">0.f</span><span class="p">);</span>
<span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setMassSpaceInertiaTensor</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">));</span>
</pre></div>
</div>
<p>This example retains the previous behavior of the turbine spinning at a constant angular velocity indefinitely. However, now the body's velocities cannot be affected by any constraints because the body has infinite mass and inertia. If a body collided with the turbine blade, the collision would behave as if the turbine blade was a kinematic body.</p>
<p>Another alternative would be to make the turbine have infinite mass and limit its rotation to just around the body's local z-axis. This would provide the same effect as applying a revolute joint between the turbine and the static windmill frame:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setMass</span><span class="p">(</span><span class="mf">0.f</span><span class="p">);</span>
<span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setMassSpaceInertiaTensor</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">,</span> <span class="mf">10.f</span><span class="p">));</span>
</pre></div>
</div>
<p>In both examples, the body's mass was set to 0, indicating that the body has infinite mass so its linear velocity cannot be changed by any constraints. However, in this example, the body's inertia is configured to permit the body's angular velocity to be affected by constraints around one principal axis or inertia. This provides a similar effect to introducing a revolute joint. The value of the inertia around the z-axis can be increased or decreased to make the turbines more/less resistive to motion.</p>
</div>
<div class="section" id="applying-forces-and-torques">
<h2>Applying Forces and Torques<a class="headerlink" href="#applying-forces-and-torques" title="Permalink to this headline">¶</a></h2>
<p>The most physics-friendly way to interact with a body is to apply a force to it. In classical mechanics, most interactions between bodies are typically solved by using forces. Because of the law:</p>
<blockquote>
<div>f = m*a (force = mass * acceleration)</div></blockquote>
<p>Forces directly control a body's acceleration, but its velocity and position only indirectly. For this reason control by force may be inconvenient if you need immediate response. The advantage of forces is that regardless of what forces you apply to the bodies in the scene, the simulation will be able to keep all the defined constraints (joints and contacts) satisfied. For example gravity works by applying a force to bodies.</p>
<p>Unfortunately applying large forces to articulated bodies at the resonant frequency of a system may lead to ever increasing velocities, and eventually to the failure of the solver to maintain the joint constraints. This is not unlike a real world system, where the joints would ultimately break.</p>
<p>The forces acting on a body are accumulated before each simulation frame, applied to the simulation, and then reset to zero in preparation for the next frame. The relevant methods of PxRigidBody and PxRigidBodyExt are listed below. Please refer to the API reference for more detail:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">addForce</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">force</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span>
<span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">addTorque</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">torque</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span>

<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addForceAtPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&amp;</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">force</span><span class="p">,</span>
    <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span>
<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addForceAtLocalPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&amp;</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">force</span><span class="p">,</span>
    <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span>
<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addLocalForceAtPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&amp;</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">force</span><span class="p">,</span>
    <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span>
<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addLocalForceAtLocalPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&amp;</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">force</span><span class="p">,</span>
    <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span>
</pre></div>
</div>
<p>The PxForceMode member defaults to PxForceMode::eFORCE to apply simple forces. There are other possibilities. For example PxForceMode::eIMPULSE will apply an impulsive force. PxForceMode::eVELOCITY_CHANGE will do the same, but also ignore the mass of the body, effectively leading to an instantaneous velocity change. See the API documentation of PxForceMode for the other possibilities.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The methods in PxRigidBodyExt support only the force modes eFORCE and eIMPULSE.</p>
</div>
<p>There are further extension functions that compute the linear and angular velocity changes that would arise in the next simulation frame if an impulsive force or impulsive torque were to be applied:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">computeVelocityDeltaFromImpulse</span><span class="p">(</span><span class="k">const</span> <span class="n">PxRigidBody</span><span class="o">&amp;</span> <span class="n">body</span><span class="p">,</span>
    <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">impulsiveForce</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">impulsiveTorque</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">deltaLinearVelocity</span><span class="p">,</span>
    <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">deltaAngularVelocity</span><span class="p">);</span>
</pre></div>
</div>
<p>A use case for this function might be to predict an updated velocity for an object so that asset loading may be initiated in advance of the simulation frame if the body is likely to exceed a threshold velocity at the end of the frame.  The impulsive force and torque are simply the force and torque that are to be applied to the body multiplied by the timestep of the simulation frame.  Neglecting the effect of constraint and contact forces, the change in linear and angular velocity that are expected to arise in the next simulation frame are returned in deltaLinearVelocity and deltaAngularVelocity.  The predicted linear velocity can then be computed with body.getLinearVelocity() + deltaLinearVelocity, while the predicted angular velocity can be computed with body.getAngularVelocity() + deltaAngularVelocity.  If required, it is possible to immediately update the velocity of the body using body.setLinearVelocity(body.getLinearVelocity() + deltaLinearVelocity) and body.setAngularVelocity(body.getAngularVelocity() + deltaAngularVelocity).</p>
</div>
<div class="section" id="gravity">
<h2>Gravity<a class="headerlink" href="#gravity" title="Permalink to this headline">¶</a></h2>
<p>Gravity is such a common force in simulations that PhysX makes it particularly simple to apply. For a scene-wide gravity effect, or any other uniform force field, set the PxScene class' gravity vector using PxScene::setGravity().</p>
<p>The parameter is the acceleration due to gravity. In meters and seconds, this works out to have a magnitude of about 9.8 on earth, and should point downwards. The force that will be applied at the center of mass of each body in the scene is this acceleration vector times the actor's mass.</p>
<p>Certain special effects can require that some dynamic actors are not influenced by gravity. To specify this set the flag:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxActor</span><span class="o">::</span><span class="n">setActorFlag</span><span class="p">(</span><span class="n">PxActorFlag</span><span class="o">::</span><span class="n">eDISABLE_GRAVITY</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Be careful when changing gravity (or enabling/disabling it) during the simulation. For performance reasons the change will not wake up sleeping actors automatically. Thus it may be necessary to iterate through all actors and call PxRigidDynamic::wakeUp() manually.</p>
</div>
<p>An alternative to PxActorFlag::eDISABLE_GRAVITY is to use a zero gravity vector for the whole scene, then apply your own gravity force to rigid bodies, each frame. This can be used to create radial gravity fields, as demonstrated in SampleCustomGravity.</p>
</div>
<div class="section" id="friction-and-restitution">
<h2>Friction and Restitution<a class="headerlink" href="#friction-and-restitution" title="Permalink to this headline">¶</a></h2>
<p>All physical objects have at least one material, which defines the friction and restitution properties used to resolve a collision with the objects.</p>
<p>To create a material, call PxPhysics::createMaterial():</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxMaterial</span><span class="o">*</span> <span class="n">mMaterial</span><span class="p">;</span>

<span class="n">mMaterial</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-&gt;</span><span class="n">createMaterial</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">,</span> <span class="mf">0.5f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">);</span> <span class="c1">// static friction, dynamic friction,</span>
                                                        <span class="c1">// restitution</span>
<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">mMaterial</span><span class="p">)</span>
    <span class="n">fatalError</span><span class="p">(</span><span class="s">&quot;createMaterial failed!&quot;</span><span class="p">);</span>
</pre></div>
</div>
<p>Materials are owned by the PxPhysics object, and can be shared among objects in multiple scenes. The material properties of two objects involved in a collision may be combined in various ways. See the reference documentation for PxMaterial for more details.</p>
<p>PhysX objects whose collision geometry is a triangle mesh or a heightfield (see <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollisionshapes"><em>Shapes</em></a>) can have a material per triangle.</p>
<p>Friction uses the coulomb friction model, which is based around the concepts of 2 coefficients: the static friction coefficient and the dynamic friction coefficient (sometimes called kinetic friction). Friction resists relative lateral motion of two solid surfaces in contact. These two coefficients define a relationship between the normal force exerted by each surface on the other and the amount of friction force that is applied to resist lateral motion. Static friction defines the amount of friction that is applied between surfaces that are not moving lateral to each-other. Dynamic friction defines the amount of friction applied between surfaces that are moving relative to each-other.</p>
<p>When using the default patch friction model, PhysX's friction model is, by default, stronger than analytical models. To achieve results much closer to analytical models, PhysX 4.0 introduced the PxMaterialFlag::eIMPROVED_PATCH_FRICTION flag. By default, this flag is not enabled to maintain legacy behavior.</p>
<p>The coefficient of restitution of two colliding objects is a fractional value representing the ratio of speeds after and before an impact, taken along the line of impact. A coefficient of restitution of 1 is said to collide elastically, while a coefficient of restitution &lt; 1 is said to be inelastic.</p>
</div>
<div class="section" id="sleeping">
<span id="id1"></span><h2>Sleeping<a class="headerlink" href="#sleeping" title="Permalink to this headline">¶</a></h2>
<p>When an actor does not move for a period of time, it is assumed that it will not move in the future either until some external force acts on it that throws it out of equilibrium. Until then it is no longer simulated in order to save resources. This state is called sleeping. You can query an actor's sleep state with the following method:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">isSleeping</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
</pre></div>
</div>
<p>It is however often more convenient to listen for events that the SDK sends when actors fall asleep or wake up.  To receive the following events, PxActorFlag::eSEND_SLEEP_NOTIFIES must be set for the actor:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onWake</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onSleep</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
</pre></div>
</div>
<p>See the section <a class="reference internal" href="Simulation.html#callbacks"><em>Callback Sequence</em></a> and the subsection <a class="reference internal" href="#sleep-callbacks"><em>Sleep state change events</em></a> for more information.</p>
<p>An actor goes to sleep when its kinetic energy is below a given threshold for a certain time. Basically, every dynamic rigid actor has a wake counter which gets decremented by the simulation time step when the kinetic energy of the actor is below the specified threshold. However, if the energy is above the threshold after a simulation step, the counter gets reset to a minimum default value and the whole process starts anew. Once the wake counter reaches zero, it does not get decremented any further and the actor is ready to go to sleep. Please note that a zero wake counter does not mean that the actor has to be asleep, it only indicates that it is ready to go to sleep. There are other factors that might keep an actor awake for a while longer.</p>
<p>The energy threshold as well as the minimum amount of time an actor will stay awake can be manipulated using the following methods:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">setSleepThreshold</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">threshold</span><span class="p">);</span>
<span class="n">PxReal</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">getSleepThreshold</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>

<span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">setWakeCounter</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">wakeCounterValue</span><span class="p">);</span>
<span class="n">PxReal</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">getWakeCounter</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For kinematic actors, special sleep rules apply. A kinematic actor is asleep unless a target pose has been set (in which case it will stay awake until the end of the next simulation step where no target pose has been set anymore). As a consequence, it is not allowed to use setWakeCounter() for kinematic actors. The wake counter of a kinematic actor is solely defined based on whether a target pose has been set.</p>
</div>
<p>If a dynamic rigid actor is sleeping, the following state is guaranteed:</p>
<ul class="simple">
<li>The wake counter is zero.</li>
<li>The linear and angular velocity is zero.</li>
<li>There is no force update pending.</li>
</ul>
<p>When an actor gets inserted into a scene, it will be considered asleep if all the points above hold, else it will be treated as awake.</p>
<p>In general, a dynamic rigid actor is guaranteed to be awake if at least one of the following holds:</p>
<ul class="simple">
<li>The wake counter is positive.</li>
<li>The linear or angular velocity is non-zero.</li>
<li>A non-zero force or torque has been applied.</li>
</ul>
<p>As a consequence, the following calls will wake the actor up automatically:</p>
<ul class="simple">
<li>PxRigidDynamic::setWakeCounter(), if the wake counter value is larger than zero.</li>
<li>PxRigidBody::setLinearVelocity(), ::setAngularVelocity(), if the velocity is non-zero.</li>
<li>PxRigidBody::addForce(), ::addTorque(), if the torque is non-zero.</li>
</ul>
<p>In addition, the following calls and events wake an actor up:</p>
<ul class="simple">
<li>PxRigidDynamic::setKinematicTarget() in the case of a kinematic actor (because this also sets the wake counter to a positive value).</li>
<li>PxRigidActor::setGlobalPose(), if the autowake parameter is set to true (default).</li>
<li>Simulation gets disabled for a PxRigidActor by raising PxActorFlag::eDISABLE_SIMULATION.</li>
<li>PxScene::resetFiltering().</li>
<li>PxShape::setSimulationFilterData(), if the subsequent re-filtering causes the type of the shape pair to transition between suppressed, trigger and contact.</li>
<li>Touch with an actor that is awake.</li>
<li>A touching rigid actor gets removed from the scene (this is the default behavior but it can be specified by the user, see note further below).</li>
<li>Contact with a static rigid actor is lost.</li>
<li>Contact with a dynamic rigid actor is lost and this actor is awake in the next simulation step.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When removing a rigid actor from the scene or a shape from an actor, it is possible to specify whether to wake up the objects that were touching the removed object in the previous simulation step. See the API comments in PxScene::removeActor() and PxRigidActor::detachShape() for details.</p>
</div>
<p>To explicitly wake up a sleeping object, or force an object to sleep, use:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">wakeUp</span><span class="p">();</span>
<span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">putToSleep</span><span class="p">();</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is not allowed to use these methods for kinematic actors. The sleep state of a kinematic actor is solely defined based on whether a target pose has been set.</p>
</div>
<p>The API reference documents exactly which methods cause an actor to be woken up.</p>
<div class="section" id="sleep-state-change-events">
<span id="sleep-callbacks"></span><h3>Sleep state change events<a class="headerlink" href="#sleep-state-change-events" title="Permalink to this headline">¶</a></h3>
<p>As mentioned above, PhysX provides an event system that reports changes to the sleep state of dynamic rigid bodies during <em>PxScene::fetchResults()</em>:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onWake</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onSleep</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
</pre></div>
</div>
<p>It is important to understand the correct usage of these events, and their limitations:</p>
<ul class="simple">
<li>A body added since the previous <em>fetchResults()</em> or <em>flushSimulation()</em> will always generate an event, even if no sleep state transition occured.</li>
<li>If there have been multiple changes in a body's sleep state since the previous <em>fetchResults()</em> or <em>flushSimulation()</em>, PhysX will report only the most recent.</li>
</ul>
<p>Sometimes it is desirable to detect transitions between awake and asleep, e.g. when keeping track of the number of awake bodies. Suppose a sleeping body <em>B</em> is woken by the application, the counter is incremented, and during the next simulation step <em>B</em> stays awake. Even though <em>B</em>'s sleep state did not change during simulation, it has changed since the previous <em>fetchResults()</em>, and so an <em>onWake()</em> event will be generated for it. If the counter is incremented again in response to this event, its value will be incorrect.</p>
<p>To use sleep state events to detect transitions, a record of the sleep state for objects of interest has to be kept, for example in a hash. When processing an event, this record can be used to check whether there has been a transition.</p>
</div>
</div>
<div class="section" id="kinematic-actors">
<h2>Kinematic Actors<a class="headerlink" href="#kinematic-actors" title="Permalink to this headline">¶</a></h2>
<p>Sometimes controlling an actor using forces or constraints is not sufficiently robust, precise or flexible. For example moving platforms or character controllers often need to manipulate an actor's position or have it exactly follow a specific path. Such a control scheme is provided by kinematic actors.</p>
<p>A kinematic actor is controlled using the PxRigidDynamic::setKinematicTarget() function. Each simulation step PhysX moves the actor to its target position, regardless of external forces, gravity, collision, etc. Thus one must continually call setKinematicTarget(), every time step, for each kinematic actor, to make them move along their desired paths. The movement of a kinematic actor affects dynamic actors with which it collides or to which it is constrained with a joint. The actor will appear to have infinite mass and will push regular dynamic actors out of the way.</p>
<p>To create a kinematic actor, simply create a regular dynamic actor then set its kinematic flag:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidBody</span><span class="o">::</span><span class="n">setRigidBodyFlag</span><span class="p">(</span><span class="n">PxRigidBodyFlag</span><span class="o">::</span><span class="n">eKINEMATIC</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span>
</pre></div>
</div>
<p>Use the same function to transform a kinematic actor back to a regular dynamic actor. While you do need to provide a mass for the kinematic actor as for all dynamic actors, this mass will not actually be used for anything while the actor is in kinematic mode.</p>
<p>Caveats:</p>
<ul class="simple">
<li>It is important to understand the difference between PxRigidDynamic::setKinematicTarget() and PxRigidActor::setGlobalPose() here. While setGlobalPose() would also move the actor to the desired position, it would not make that actor properly interact with other objects. In particular, with setGlobalPose() the kinematic actor would not push away other dynamic actors in its path, instead it would go right through them. The setGlobalPose() function can still be used though, if one simply wants to teleport a kinematic actor to a new position.</li>
<li>A kinematic actor can push away dynamic objects, but nothing pushes it back. As a result, a kinematic can easily squish a dynamic actor against a static actor, or against another kinematic actor. As a result, the squished dynamic object can deeply penetrate the geometry it has been pushed into.</li>
<li>There is no interaction or collision between kinematic actors and static actors. However, it is possible to request contact information for these cases with the PxSceneDesc::kineKineFilteringMode and PxSceneDesc::staticKineFilteringMode.</li>
</ul>
<div class="section" id="kinematic-surface-velocities">
<h3>Kinematic Surface Velocities<a class="headerlink" href="#kinematic-surface-velocities" title="Permalink to this headline">¶</a></h3>
<p>In addition to setting kinematic targets or the global pose of a kinematic actor, it is also possible to set a kinematic surface velocity using the method PxRigidDynamic::setKinematicSurfaceVelocity(). This method is only legal to call if the rigid body in question is set to be kinematic. This method sets a persistent velocity on the kinematic actor but flags the actor to bypass integration. This means that objects interacting with the kinematic actor through collisions will behave as if the kinematic actor is moving, although the actor's pose does not actually change. This mechanism can be used to create conveyor belts and rotating surfaces.</p>
</div>
</div>
<div class="section" id="active-actors">
<h2>Active Actors<a class="headerlink" href="#active-actors" title="Permalink to this headline">¶</a></h2>
<p>The active actors API provides an efficient way to reflect actor transform changes in a PhysX scene to an associated external object such as a render mesh.</p>
<p>When a scene's fetchResults() method is called an array of active <em>PxActor</em> is generated. Because only actors that have moved will be included in the list this approach is potentially much more efficient than, for example, analyzing each actor in the scene individually.</p>
<p>The example below shows how to use active actors to update a render object:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// update scene</span>
<span class="n">scene</span><span class="p">.</span><span class="n">simulate</span><span class="p">(</span><span class="n">dt</span><span class="p">);</span>
<span class="n">scene</span><span class="p">.</span><span class="n">fetchResults</span><span class="p">();</span>

<span class="c1">// retrieve array of actors that moved</span>
<span class="n">PxU32</span> <span class="n">nbActiveActors</span><span class="p">;</span>
<span class="n">PxActor</span><span class="o">**</span> <span class="n">activeActors</span> <span class="o">=</span> <span class="n">scene</span><span class="p">.</span><span class="n">getActiveActors</span><span class="p">(</span><span class="n">nbActiveActors</span><span class="p">);</span>

<span class="c1">// update each render object with the new transform</span>
<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">nbActiveActors</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
<span class="p">{</span>
    <span class="n">MyRenderObject</span><span class="o">*</span> <span class="n">renderObject</span> <span class="o">=</span> <span class="k">static_cast</span><span class="o">&lt;</span><span class="n">MyRenderObject</span><span class="o">*&gt;</span><span class="p">(</span><span class="n">activeActors</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-&gt;</span><span class="n">userData</span><span class="p">);</span>
    <span class="n">renderObject</span><span class="o">-&gt;</span><span class="n">setTransform</span><span class="p">(</span><span class="n">activeActors</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-&gt;</span><span class="n">getGlobalPose</span><span class="p">());</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">PxSceneFlag::eENABLE_ACTIVE_ACTORS must be set on the scene for the active actors array to be generated.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Since the target transform for kinematic rigid bodies is set by the user, kinematics can be excluded from the list by setting the flag PxSceneFlag::eEXCLUDE_KINEMATICS_FROM_ACTIVE_ACTORS.</p>
</div>
</div>
<div class="section" id="dominance">
<h2>Dominance<a class="headerlink" href="#dominance" title="Permalink to this headline">¶</a></h2>
<p>Dominance is a mechanism to enable dynamic bodies to dominate each-other. Dominance effectively imbues the dominant body in a pair with infinite mass. This is a form of local mass modification within the constraint solver and, as such, can override the mass of one of the bodies in a pair. Similar effects can be achieved through local mass modification in contact modification but dominance has the advantage of being handled automatically within the SDK so does not incur the additional memory and performance overhead of contact modification.</p>
<p>Each actor must be assigned a dominance group ID. This is a 5-bit value in the range [0, 31]. As such, you are restricted to at-most 32 dominance groups. By default, all bodies are placed in dominance group 0. An actor can be assigned to a dominance group using the following method on PxActor:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">setDominanceGroup</span><span class="p">(</span><span class="n">PxDominanceGroup</span> <span class="n">dominanceGroup</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
</pre></div>
</div>
<p>Dominance is defined by 2 real numbers in the following struct:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">PxDominanceGroupPair</span>
<span class="p">{</span>
    <span class="n">PxDominanceGroupPair</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">a</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">b</span><span class="p">)</span>
        <span class="o">:</span> <span class="n">dominance0</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="n">dominance1</span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="p">{}</span>
    <span class="n">PxReal</span> <span class="n">dominance0</span><span class="p">;</span>
    <span class="n">PxReal</span> <span class="n">dominance1</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>And dominance between two dominance groups can be configured using the following method on PxScene:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">setDominanceGroupPair</span><span class="p">(</span><span class="n">PxDominanceGroup</span> <span class="n">group1</span><span class="p">,</span> <span class="n">PxDominanceGroup</span> <span class="n">group2</span><span class="p">,</span>
    <span class="k">const</span> <span class="n">PxDominanceGroupPair</span><span class="o">&amp;</span> <span class="n">dominance</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
</pre></div>
</div>
<p>The user can define 3 different states for a given PxDominanceGroupPair:
* 1 : 1. This indicates that both bodies have equal dominance. This is the default behavior.
* 1 : 0. This indicates that body B dominates body A.
* 0 : 1. This indicates that body A dominates body B.</p>
<p>Any values other than 0 and 1 are not valid in a PxDominanceGroupPair. Assigning 0 to both sides of the PxDominanceGroupPair is also invalid. These values can be considered to be scales applied to the bodies' respective inverse mass and inverse inertia. A dominance value of 0 would therefore equate to an infinite mass body.</p>
<p>The following example sets two actors, actorA and actorB, into different dominance groups and configures the dominance group to make actorA dominate actorB:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">actorA</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-&gt;</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span>
<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">actorB</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-&gt;</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span>

<span class="n">actorA</span><span class="o">-&gt;</span><span class="n">setDominanceGroup</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="n">actorB</span><span class="o">-&gt;</span><span class="n">setDominanceGroup</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span>

<span class="n">mScene</span><span class="o">-&gt;</span><span class="n">setDominanceGroupPair</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">PxDominanceGroupPair</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">1.f</span><span class="p">));</span>
</pre></div>
</div>
<p>Dominance values will not affect joints. Local mass modification on joints must be performed using the following methods on PxJoint:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvMassScale0</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invMassScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvMassScale1</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invMassScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvInertiaScale0</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invInertiaScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvInertiaScale1</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invInertiaScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
</pre></div>
</div>
<p>As previously mentioned, dominance does not permit values other than 0 or 1 and any dominance values are applied uniformly to both the inverse mass and inverse inertia. Joints and contacts through contact modification permit defining separate inverse mass and inverse inertia scales, which accept any values within the range [0, PX_MAX_REAL] so can be used to achieve a wider range of effects than dominance can.</p>
<p>Dominance can produce some very peculiar results if misused. For example, given bodies A, B and C configured in the following way:</p>
<ul class="simple">
<li>Body A dominates body B</li>
<li>Body B dominance body C</li>
<li>Body C dominates body A</li>
</ul>
<p>In this situation, body A cannot push body C directly. However, it can push body C if it pushes body B into body C.</p>
</div>
<div class="section" id="solver-iterations">
<h2>Solver Iterations<a class="headerlink" href="#solver-iterations" title="Permalink to this headline">¶</a></h2>
<p>When the motion of a rigid body is constrained either by contacts or joints, the constraint solver comes into play. The solver satisfies the constraints on the bodies by iterating over all the constraints restricting the motion of the body a certain number of times. The more iterations, the more accurate the results become. The solver iteration count defaults to 4 position iterations and 1 velocity iteration. Those counts may be set individually for each body using the following function:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">setSolverIterationCounts</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">minPositionIters</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">minVelocityIters</span><span class="p">);</span>
</pre></div>
</div>
<p>Typically it is only necessary to significantly increase these values for objects with lots of joints and a small tolerance for joint error. If you find a need to use a setting higher than 30, you may wish to reconsider the configuration of your simulation.</p>
<p>The solver groups contacts into friction patches; friction patches are groups of contacts which share the same materials and have similar contact normals. However, the solver permits a maximum of 32 friction patches per contact manager (pair of shapes). If more than 32 friction patches are produced, which may be due to very complex collision geometry or very large contact offsets, the solver will ignore the remaining friction patches. A warning will be issues in checked/debug builds when this happens.</p>
</div>
<div class="section" id="immediate-mode">
<h2>Immediate Mode<a class="headerlink" href="#immediate-mode" title="Permalink to this headline">¶</a></h2>
<p>In addition to simulation using a <em>PxScene</em>, <em>PhysX</em> offers a low-level simulation API called &quot;immediate mode&quot;. This provides an API to access the low-level contact generation and constraint solver. This approach currently only supports CPU rigid bodies and reduced coordinate articulations. It does not support maximal coordinate articulations.</p>
<p>The immediate mode API is defined in <em>PxImmediateMode.h</em> and there are two Snippets demonstrating its usage: &quot;SnippetImmediateMode&quot; and &quot;SnippetImmediateArticulation&quot;. The first one does not use articulations and shows how to use the API for rigid bodies and joints that still belong to a <em>PxScene</em>. This can be used e.g. to simulate a specific actor of a scene with a higher frequency than the rest of the scene. The second snippet is a &quot;pure&quot; immediate mode example where all involved actors, joints and articulations exist without the need for <em>PxScene</em>, <em>PxActor</em> or <em>PxArticulation</em> objects.</p>
<p>The immediate mode API provides a function to perform contact generation:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxGenerateContacts</span><span class="p">(</span><span class="k">const</span> <span class="n">PxGeometry</span><span class="o">*</span> <span class="k">const</span> <span class="o">*</span> <span class="n">geom0</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxGeometry</span><span class="o">*</span> <span class="k">const</span> <span class="o">*</span> <span class="n">geom1</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxTransform</span><span class="o">*</span> <span class="n">pose0</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxTransform</span><span class="o">*</span> <span class="n">pose1</span><span class="p">,</span> <span class="n">PxCache</span><span class="o">*</span> <span class="n">contactCache</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbPairs</span><span class="p">,</span> <span class="n">PxContactRecorder</span><span class="o">&amp;</span> <span class="n">contactRecorder</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">contactDistance</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">meshContactMargin</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">toleranceLength</span><span class="p">,</span> <span class="n">PxCacheAllocator</span><span class="o">&amp;</span> <span class="n">allocator</span><span class="p">);</span>
</pre></div>
</div>
<p>This function takes a set of pairs of <em>PxGeometry</em> objects located at specific poses and performs collision detection between the pairs. If the pair of geometries collide, contacts are generated, which are reported to <em>contactRecorder</em>. In addition, information may be cached in <em>contactCache</em> to accelerate future queries between these pairs of geometries. Any memory required for this cached information will be allocated using <em>allocator</em>.</p>
<p>In addition, the immediate mode provides APIs for the constraint solver. These include functions to create bodies used by the solver:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxConstructSolverBodies</span><span class="p">(</span><span class="k">const</span> <span class="n">PxRigidBodyData</span><span class="o">*</span> <span class="n">inRigidData</span><span class="p">,</span> <span class="n">PxSolverBodyData</span><span class="o">*</span> <span class="n">outSolverBodyData</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBodies</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">gravity</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">);</span>

<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxConstructStaticSolverBody</span><span class="p">(</span><span class="k">const</span> <span class="n">PxTransform</span><span class="o">&amp;</span> <span class="n">globalPose</span><span class="p">,</span> <span class="n">PxSolverBodyData</span><span class="o">&amp;</span> <span class="n">solverBodyData</span><span class="p">);</span>
</pre></div>
</div>
<p>In addition to constructing the bodies, <em>PxConstructSolverBodies</em> also integrates the provided gravitational acceleration into the bodies velocities.</p>
<p>The following function is optional and is used to batch constraints:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="n">PxU32</span> <span class="nf">PxBatchConstraints</span><span class="p">(</span> <span class="k">const</span> <span class="n">PxSolverConstraintDesc</span><span class="o">*</span> <span class="n">solverConstraintDescs</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbConstraints</span><span class="p">,</span> <span class="n">PxSolverBody</span><span class="o">*</span> <span class="n">solverBodies</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBodies</span><span class="p">,</span>
                                                                                                                <span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">outBatchHeaders</span><span class="p">,</span> <span class="n">PxSolverConstraintDesc</span><span class="o">*</span> <span class="n">outOrderedConstraintDescs</span><span class="p">,</span>
                                                                                                                <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">**</span> <span class="n">articulations</span><span class="o">=</span><span class="nb">NULL</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbArticulations</span><span class="o">=</span><span class="mi">0</span><span class="p">);</span>
</pre></div>
</div>
<p>Batching constraints reorders the provided constraints and produces batchHeaders, which can be used by the solver to accelerate constraint solving by grouping together independent constraints and solving them in parallel using multiple lanes in SIMD registers. This process is entirely optional and can bypassed if not desired. Note that this will change the order in which constraints are processed, which can change the outcome of the solver.</p>
<p>The following methods is provided to create contact constraints:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxCreateContactConstraints</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeaders</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbHeaders</span><span class="p">,</span> <span class="n">PxSolverContactDesc</span><span class="o">*</span> <span class="n">contactDescs</span><span class="p">,</span>
        <span class="n">PxConstraintAllocator</span><span class="o">&amp;</span> <span class="n">allocator</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invDt</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">bounceThreshold</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">frictionOffsetThreshold</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">correlationDistance</span><span class="p">);</span>
</pre></div>
</div>
<p>This method can be provided with the contacts produced by <em>PxGenerateContacts</em> or by contacts produced by application-specific contact generation approaches.</p>
<p>The following methods are provided to create joint constraints:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxCreateJointConstraints</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeaders</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbHeaders</span><span class="p">,</span> <span class="n">PxSolverConstraintPrepDesc</span><span class="o">*</span> <span class="n">jointDescs</span><span class="p">,</span> <span class="n">PxConstraintAllocator</span><span class="o">&amp;</span> <span class="n">allocator</span><span class="p">,</span>
                                                                                                                        <span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invDt</span><span class="p">);</span>

<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxCreateJointConstraintsWithShaders</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeaders</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBatchHeaders</span><span class="p">,</span> <span class="n">PxConstraint</span><span class="o">**</span> <span class="n">constraints</span><span class="p">,</span> <span class="n">PxSolverConstraintPrepDesc</span><span class="o">*</span> <span class="n">jointDescs</span><span class="p">,</span>
                                                                                                                                                <span class="n">PxConstraintAllocator</span><span class="o">&amp;</span> <span class="n">allocator</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invDt</span><span class="p">);</span>

<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxCreateJointConstraintsWithImmediateShaders</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeaders</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBatchHeaders</span><span class="p">,</span> <span class="n">immConstraint</span><span class="o">*</span> <span class="n">constraints</span><span class="p">,</span> <span class="n">PxSolverConstraintPrepDesc</span><span class="o">*</span> <span class="n">jointDescs</span><span class="p">,</span>
                                                                                                                                                                <span class="n">PxConstraintAllocator</span><span class="o">&amp;</span> <span class="n">allocator</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invDt</span><span class="p">);</span>
</pre></div>
</div>
<p>The methods provide a mechanism for the application to define joint rows or for the application to make use of <em>PhysX PxConstraint</em> objects, which create the constraint rows.</p>
<p>The following method solves the constraints:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxSolveConstraints</span><span class="p">(</span><span class="k">const</span> <span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeaders</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBatchHeaders</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxSolverConstraintDesc</span><span class="o">*</span> <span class="n">solverConstraintDescs</span><span class="p">,</span>
        <span class="k">const</span> <span class="n">PxSolverBody</span><span class="o">*</span> <span class="n">solverBodies</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">linearMotionVelocity</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">angularMotionVelocity</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbSolverBodies</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbPositionIterations</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbVelocityIterations</span><span class="p">,</span>
        <span class="k">const</span> <span class="kt">float</span> <span class="n">dt</span><span class="o">=</span><span class="mf">0.0f</span><span class="p">,</span> <span class="k">const</span> <span class="kt">float</span> <span class="n">invDt</span><span class="o">=</span><span class="mf">0.0f</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbSolverArticulations</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">**</span> <span class="n">solverArticulations</span><span class="o">=</span><span class="nb">NULL</span><span class="p">);</span>
</pre></div>
</div>
<p>This method performs all required position and velocity iterations and updates the objects' delta velocities and motion velocities, which are stored in <em>PxSolverBody</em> and <em>linear/angularMotionVelocity</em> respectively.</p>
<p>The following method is provided to integrate the bodies' final poses and update the bodies' velocities to reflect the motion produced by the constraint solver:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxIntegrateSolverBodies</span><span class="p">(</span><span class="n">PxSolverBodyData</span><span class="o">*</span> <span class="n">solverBodyData</span><span class="p">,</span> <span class="n">PxSolverBody</span><span class="o">*</span> <span class="n">solverBody</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">linearMotionVelocity</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">angularMotionState</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBodiesToIntegrate</span><span class="p">,</span>
<span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">);</span>
</pre></div>
</div>
<p>The above methods are the ones needed for simulating regular rigid bodies and joints in immediate mode. See SnippetImmediateMode for an example.</p>
<p>Additional functions are provided to simulate reduced coordinate articulations. First, register articulation-related solver functions with <em>PxRegisterImmediateArticulations</em>:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxRegisterImmediateArticulations</span><span class="p">();</span>
</pre></div>
</div>
<p>This is the counterpart of <em>PxRegisterArticulationsReducedCoordinate</em> for immediate mode. You only need to call it once at the start of your program. Then create a low-level reduced coordinate articulations with the following function:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">*</span>        <span class="n">PxCreateFeatherstoneArticulation</span><span class="p">(</span><span class="k">const</span> <span class="n">PxFeatherstoneArticulationData</span><span class="o">&amp;</span> <span class="n">data</span><span class="p">);</span>
</pre></div>
</div>
<p>Once the articulation is created, add articulation links to it with the following function:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span>        <span class="n">PxAddArticulationLink</span><span class="p">(</span><span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">*</span> <span class="n">articulation</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxFeatherstoneArticulationLinkData</span><span class="o">&amp;</span> <span class="n">data</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">isLastLink</span><span class="o">=</span><span class="nb">false</span><span class="p">);</span>
</pre></div>
</div>
<p>The number of links per articulation is currently limited to 64, just as with PxScene-level articulations. After all links have been added, the articulation is ready to be simulated.</p>
<p>Note that for articulations the current API is not as &quot;immediate&quot; as for rigid bodies, since the returned object is still a thin &quot;retained mode&quot; wrapper around low-level structures. This is done to make articulations easier to use: the low-level structures currently contain data for both reduced coordinate and maximal coordinate articulations, and intimate knowledge of PhysX's internals is needed to distinguish between the two. The thin wrapper makes things more accessible. On the other hand, the data is not directly owned by the user, and the following function must be called to eventually release it at the end of your program:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span>      <span class="nf">PxReleaseArticulation</span><span class="p">(</span><span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">*</span> <span class="n">articulation</span><span class="p">);</span>
</pre></div>
</div>
<p>Meanwhile there are a number of data accessor functions available:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">*</span>        <span class="n">PxGetLinkArticulation</span><span class="p">(</span><span class="k">const</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span> <span class="n">link</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="n">PxU32</span>     <span class="nf">PxGetLinkIndex</span><span class="p">(</span><span class="k">const</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span> <span class="n">link</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span>      <span class="nf">PxGetLinkData</span><span class="p">(</span><span class="k">const</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span> <span class="n">link</span><span class="p">,</span> <span class="n">PxLinkData</span><span class="o">&amp;</span> <span class="n">data</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="n">PxU32</span>     <span class="nf">PxGetAllLinkData</span><span class="p">(</span><span class="k">const</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">*</span> <span class="n">articulation</span><span class="p">,</span> <span class="n">PxLinkData</span><span class="o">*</span> <span class="n">data</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span>      <span class="nf">PxGetMutableLinkData</span><span class="p">(</span><span class="k">const</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span> <span class="n">link</span><span class="p">,</span> <span class="n">PxMutableLinkData</span><span class="o">&amp;</span> <span class="n">data</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span>      <span class="nf">PxSetMutableLinkData</span><span class="p">(</span><span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span> <span class="n">link</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxMutableLinkData</span><span class="o">&amp;</span> <span class="n">data</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span>      <span class="nf">PxGetJointData</span><span class="p">(</span><span class="k">const</span> <span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span> <span class="n">link</span><span class="p">,</span> <span class="n">PxFeatherstoneArticulationJointData</span><span class="o">&amp;</span> <span class="n">data</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span>      <span class="nf">PxSetJointData</span><span class="p">(</span><span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationLinkHandle</span> <span class="n">link</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxFeatherstoneArticulationJointData</span><span class="o">&amp;</span> <span class="n">data</span><span class="p">);</span>
</pre></div>
</div>
<p>Some of them are here to update the data at runtime, say for articulation drives. Some of them are needed to setup the articulation data for aforementioned immediate mode functions like <em>PxSolveConstraints</em>, which have been updated in <em>PhysX 4.1</em> to take additional articulation-related parameters (but which should otherwise be used the same way as for immediate mode rigid bodies).</p>
<p>The only new articulation-specific functions are otherwise:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span>      <span class="nf">PxComputeUnconstrainedVelocities</span><span class="p">(</span><span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">*</span> <span class="n">articulation</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&amp;</span> <span class="n">gravity</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">);</span>
<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span>      <span class="nf">PxUpdateArticulationBodies</span><span class="p">(</span><span class="n">Dy</span><span class="o">::</span><span class="n">ArticulationV</span><span class="o">*</span> <span class="n">articulation</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">);</span>
</pre></div>
</div>
<p>Use the first one at the start of the simulation loop to compute unconstrained velocities for each immediate mode articulations. Use the second one at the end of the simulation loop to update the articulation bodies/links after <em>PxIntegrateSolverBodies</em> has finished. Please refer to SnippetImmediateArticulation for examples.</p>
</div>
<div class="section" id="enhanced-determinism">
<h2>Enhanced Determinism<a class="headerlink" href="#enhanced-determinism" title="Permalink to this headline">¶</a></h2>
<p>PhysX provides limited deterministic simulation. Specifically, the results of the simulation will be identical between runs if simulating the exact same scene (same actors inserted in the same order) using the same time-stepping scheme and same PhysX release running on the same platform. The simulation behavior is not influenced by the number of worker threads that are used.</p>
<p>However, the results of the simulation can change if actors are inserted in a different order. In addition, the overall behavior of the simulation can change if additional actors are added or if some actors are removed from the scene. This means that the simulation of a particular collection of actors can change depending on whether other actors are present in the scene or not, irrespective of whether these actors actually interact with the collection of actors. This behavioral property is usually tolerable but there are circumstances in which it is not acceptable.</p>
<p>To overcome this issue, PhysX provides a flag: PxSceneFlag::eENABLE_ENHANCED_DETERMINISM, which provides additional levels of determinism. Specifically, provided the application inserts the actors in a deterministic order, with this flag raised, the simulation of an island will be identical regardless of any other islands in the scene. However, this mode sacrifices some performance to ensure this additional determinism.</p>
</div>
<div class="section" id="axis-locking">
<h2>Axis locking<a class="headerlink" href="#axis-locking" title="Permalink to this headline">¶</a></h2>
<p>It is possible to restrict motion along or around specific world-space axes in PhysX using PxRigidDynamicLockFlag. For example, the below code snippet demonstrates how to restrict a PxRigidDynamic to two dimensional simulation. In this case, we permit the PxRigidDynamic to rotate only around the Z-axis and to translate only along the X- and Y- axes:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">dyn</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">2.5f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">)));</span>

<span class="p">...</span>

<span class="c1">//Lock the motion</span>
<span class="n">dyn</span><span class="o">-&gt;</span><span class="n">setRigidDynamicLockFlags</span><span class="p">(</span><span class="n">PxRigidDynamicLockFlag</span><span class="o">::</span><span class="n">eLOCK_LINEAR_Z</span> <span class="o">|</span> <span class="n">PxRigidDynamicLockFlag</span><span class="o">::</span><span class="n">eLOCK_ANGULAR_X</span> <span class="o">|</span> <span class="n">PxRigidDynamicLockFlag</span><span class="o">::</span><span class="n">eLOCK_ANGULAR_Y</span><span class="p">);</span>
</pre></div>
</div>
<p>It is legal to restrict movement or rotation around any combination of the 6 degrees of freedom.</p>
</div>
<div class="section" id="temporal-gauss-seidel">
<span id="temporalgaussseidel"></span><h2>Temporal Gauss-Seidel<a class="headerlink" href="#temporal-gauss-seidel" title="Permalink to this headline">¶</a></h2>
<p>PhysX provides a default Projected Gauss-Seidel-style (PGS) solver and an optional Temporal Gauss-Seidel (TGS) solver.</p>
<p>Temporal gauss-seidel offers several advantages over the PGS-style solver:</p>
<ul class="simple">
<li>Dramatically improved convergence</li>
<li>Improved handling of high-mass ratios</li>
<li>Minimizes energy introduced when correcting penetrations (depending on solver convergence)</li>
<li>Improved joint drive accuracy</li>
</ul>
<p>TGS is generally a little slower than PGS. This is partially due to the increased complexity of the constraint solver and also partially due to TGS solving friction constraints every iteration, whereas PGS solves friction constraints only in the final 3 position iterations by default.</p>
<p>Enabling the TGS solver requires setting PxSceneDesc::solverType to PxSolverType::eTGS. This is an immutable scene property that must be set before the scene is constructed.</p>
<p>The TGS solver is available when using both CPU and GPU simulation.</p>
</div>
</div>


           </div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="Simulation.html" class="btn btn-neutral float-right" title="Simulation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="RigidBodyCollision.html" class="btn btn-neutral" title="Rigid Body Collision" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2008-2021 NVIDIA Corporation, 2788 San Tomas Expressway, Santa Clara, CA 95051 U.S.A. All rights reserved

    </p>
  </div> 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    
    
      <script type="text/javascript">
          var DOCUMENTATION_OPTIONS = {
              URL_ROOT:'../',
              VERSION:'4.1',
              LANGUAGE:'',
              COLLAPSE_INDEX:false,
              FILE_SUFFIX:'.html',
              HAS_SOURCE:  true,
              SOURCELINK_SUFFIX: ''
          };
      </script>
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
    

  

  <script type="text/javascript" src="../_static/js/theme.js"></script>

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(false);
      });
  </script> 

</body>
</html>